<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html> <head>
<title>A Brief Introduction to Epytext </title>
<link rel="stylesheet" href="epydoc.css" type="text/css"/>
</head>
<!-- $Id: epytextintro.html 1417 2007-01-17 21:41:59Z edloper $ -->

<body>
<div class="body">
<h1> A Brief Introduction to Epytext </h1>

<p> Epytext is a simple lightweight markup language that lets you add
formatting and structure to docstrings.  Epydoc uses that formatting
and structure to produce nicely formatted API documentation.  The
following example (which has an unusually high ratio of documentaiton
to code) illustrates some of the basic features of epytext: </p>

<div class="screen"><pre>
<code class="keyword">def</code> <code class="function">x_intercept</code>(m, b):
    <code class="string">"""
    Return the x intercept of the line M{y=m*x+b}.  The X{x intercept}
    of a line is the point at which it crosses the x axis (M{y=0}).

    This function can be used in conjuction with L{z_transform} to
    find an arbitrary function's zeros.

    <code class="field">@type  m:</code> number
    <code class="field">@param m:</code> The slope of the line.
    <code class="field">@type  b:</code> number
    <code class="field">@param b:</code> The y intercept of the line.  The X{y intercept} of a
              line is the point at which it crosses the y axis (M{x=0}).
    <code class="field">@rtype:</code>   number
    <code class="field">@return:</code>  the x intercept of the line M{y=m*x+b}.
    """</code>
    <code class="keyword">return</code> -b/m
</pre></div>

<p> You can compare this function definition with the <a
href="examples/epytext_example-module.html#x_intercept" target="_blank">API
documentation</a> generated by epydoc.  Note that: </p>

<ul>
  <li> Paragraphs are separated by blank lines. </li>
  <li> Inline markup has the form "<i>x</i><code>{...}</code>", where
  "<i>x</i>" is a single capital letter.  This example uses
  inline markup to mark mathematical expressions
  ("<code>M{...}</code>"); terms that should be indexed
  ("<code>X{...}</code>"); and links to the documentation of
  other objects ("<code>L{...}</code>"). </li>
  <li> Descriptions of parameters, return values, and types are
  marked with "<code>@<i>field</i>:</code>" or
  "<code>@<i>field</i>&nbsp<i>arg</i>:</code>", where
  "<code><i>field</i></code>" identifies the kind of description, and
  "<code><i>arg</i></code>" specifies what object is described. </li>
</ul>

<p> For more information about the epytext markup language, see the <a
href="epytext.html">epytext manual</a>.  Epytext is intentionally very
lightweight.  If you wish to use a more expressive markup language, I
recommend <a href="othermarkup.html">reStructuredText</a>. </p>

</div>
<table width="100%" class="navbox" cellpadding="1" cellspacing="0">
  <tr>
  <a class="nav" href="index.html">
    <td align="center" width="20%" class="nav">
    <a class="nav" href="index.html">
    Home</a></td></a>
  <a class="nav" href="installing.html">
    <td align="center" width="20%" class="nav">
    <a class="nav" href="installing.html">
    Installing Epydoc</a></td></a>
  <a class="nav" href="using.html">
    <td align="center" width="20%" class="nav">
    <a class="nav" href="using.html">
    Using Epydoc</a></td></a>
  <a class="nav" href="epytext.html">
    <td align="center" width="20%" class="nav">
    <a class="nav" href="epytext.html">
    Epytext</a></td></a>
  <td align="center" width="20%" class="nav">
    
    <A href="http://sourceforge.net/projects/epydoc"> 
    <IMG src="sflogo.png" 
    width="88" height="26" border="0" alt="SourceForge"
    align="top"/></A></td>
    </tr>
</table>
</body>
</html>
